The Controls

A standard button allowing you to run a Script when clicked by the user.

The Map to Back Key Property allows you to map a Button to the device's Back key or to a virtual Back key.

Android Devices

If this Property is set to True for a Control, when the user presses the device's Back key, this will simulate tapping or clicking the mapped Control rather than performing the Back key's standard function.

On forms which have a control mapped to the Back key, the Back key can no longer be used to return to the applications page within the Digitise Apps Client. You can, however, always return to the applications page from the menu available by tapping the menu icon, , at the bottom of the screen.

Apple and Windows Devices

These devices don't have a hard Back key so setting this Property to True will display a Back button on the left-hand side of the title bar (besides the Home button) instead. Tapping or clicking the button will simulate tapping/clicking the mapped Control.

The Back button will only be displayed on forms which have a Control mapped to the Back key, so if you want the button to be displayed on all screens, you will need to map a Control on each form.

In all cases, if the mapped control has a Script assigned to its OnClick Event, this Script will run and then any implicit behaviour in the Control will be performed, e.g. a Next Button navigating to the next form.

By default, the Property is set to False which disables the mapping. If you set this Property on multiple Controls, the Control highest in the Control tree will be the one which is mapped.

Note that if this Property is set to True, the Digitise Apps Client will only action the back key if the Control is enabled.

Picture & Video Controls also have a Map to Back key Property.

Button Control with Caption pre-set to OK.

Triggers the form's OnOK Event and then automatically returns to the calling form, unless the OnOK Event returns -1. To return -1, include the line OnOK = -1 within your Script at the point at which you want to return.

The Map to Back Key Property allows you to map an OK Button to the device's Back key or to a virtual Back key. For details refer to the Button Control above.

Button Control with Caption pre-set to Cancel.

Triggers the form's OnCancel Event and then automatically returns to the calling form.

The Map to Back Key Property allows you to map an OK Button to the device's Back key or to a virtual Back key. For details refer to the Button Control above.

Button Control with Caption pre-set to <<. Clicking this button will navigate back to the previous form.

You can override the default behaviour using the SetNextForm Scripting Method in the Button's OnClick Event, if required.

The Map to Back Key Property allows you to map an OK Button to the device's Back key or to a virtual Back key. For details refer to the Button Control above.

Button Control with Caption pre-set to >>. Clicking this button will navigate to the next form.

You can override the default behaviour using the SetNextForm Scripting Method in the Button's OnClick Event, if required.

The Map to Back Key Property allows you to map an OK Button to the device's Back key or to a virtual Back key. For details refer to the Button Control above.

Navigate to next, previous or specified form.

You can override the form specified in the Button's Properties if required by using the SetNextForm Scripting Method in the Button's OnClick Event.

The Map to Back Key Property allows you to map an OK Button to the device's Back key or to a virtual Back key. For details refer to the Button Control above.

Select true/false value.

When checking the value of the Control within a Script, 1, True and "True" will all indicate that the Control is selected, i.e. contains a tick, whilst 0, False or "False" indicate that the Control is not selected.

Check boxes can be selected and deselected in the standard manner for the mobile device on which the app runs.

Display and edit text/numeric values.

To display numeric values only you need to set the Numeric Property for the Control to True.

In numeric mode, additional Properties for this Control will appear under the category Spinner, which allow you to add a Spinner Control to the Edit Box. A Spinner control provides up and down arrow buttons which can be tapped or clicked, as appropriate for the device, to move through the set of valid values for the Edit Control.

You can specify Maximum and Minimum values for the Control and the Step, which determines the amount by which the currently displayed value will be increased or decreased when one of the Spinner Arrow buttons is activated. A user will not be able to enter a value which is outside the range specified. If they attempt to do so, the Control will automatically display the maximum or minimum value as appropriate.

Numeric values can include negative numbers.

On devices which have a soft keypad, setting the edit field to numeric only, will cause the keyboard to display in number mode rather than displaying letters.

You can prevent a user from editing the contents of an Edit Control, by setting its Read-Only Property to True. Note, however, that if the Control is set to numeric mode with a spinner control added, setting the Read-Only Property to True will prevent users from editing the value within the Edit box but doesn't disable the Spinner's up and down arrows, allowing the user to change the value using the Spinner. Note also that on iOS devices, if the Edit Control is set to be read-only, the OnGetFocus and OnLoseFocus Events will not be triggered.

For alpha-numeric fields, i.e. the Numeric Property is set to False, other Properties for the Control allow you to specify a maximum number of characters for the field, to designate the field as a password field, in which case asterisks or dots will be displayed in place of the actual field contents, and to specify support for multiple lines. If the maximum number of characters is set to zero, there is no restriction on the number of characters which can be entered.

This Control allows you to display a list of potential values from which the user can choose the appropriate one for their current purposes.

There are two types of Combo Box Control:

Dropdown

Combines an Edit Box and a list of predefined items.

The user can select from the list or type directly in the Edit Box. The Control usually displays an arrow symbol at the right-hand end of the Edit Box which can be clicked or tapped, as appropriate for the device Platform, to display the list.

The Edit Box displays the current value of the Control. If the user types a value in the Edit Box which doesn't match one of the predefined values, no item will be selected.

 

Droplist

This type of Combo Box only provides a list of predefined values from which the user can select. The user cannot type into the Control.

On some Platforms, the Control displays an arrow symbol at the right-hand end of the Control which can be tapped or clicked, as appropriate, to display the list. If the Control doesn't have an arrow, the list is displayed by tapping the Control.

The Control displays the currently selected item.

 

You specify which of the two types you want the Combo Box to be using the Control's Type Property.

The list of your predefined values is entered into the Control's Caption Property. When entering the values, enter each item on a new line using Ctrl+Enter to start a new line.

On the Android Platform the appearance of a Droplist Combo Box is affected by the Android Combo Box Display Mode project-level Property. If this Property is set to Transparent, at runtime the background of the control will be transparent, i.e. the background colour of the form or other Controls behind the Combo Box will show through the Combo Box. If set to Grey, the Combo Box will have an opaque grey background colour instead. The default value is Transparent.

Display list of items from which to select one.

The Caption Property for the Control allows you to specify the values to be included within the list. When entering the values, enter each item on a new line using Ctrl+Enter to start a new line.

Select one value from a set of mutually exclusive options.

A group of associated Radio Buttons must be surrounded by a Panel Control to identify them as a single unit.

If a Radio Button group is to have input mappings, all the Controls within the group must be mapped to the same input Data Source column and, if they are to have output mappings as well, to the same output Data Source column. Each Radio Button within the group must be assigned a specific value which on an input mapping indicates which of the Radio Buttons is to be displayed as selected.

For example, suppose you have a group of three Radio Buttons mapped to a remote Data Source column which will contain an integer in the range 1 to 3. The first Radio Button could be assigned the value 1, the second 2 etc. When this group is updated in the app, e.g. when data is downloaded and the first new record is displayed, the value of this column in the record determines which Radio Button in the group is displayed as selected. So, if the value is 2 the middle Radio Button would be selected, if the value is not one of the assigned values none would be selected etc.

If the user is allowed to change or make a selection, the Radio Button selected determines the value to be output for the output mapping column. Continuing with the example above, if the middle button is selected then the output value would be 2. If no button is selected, no value is output.

The value is assigned to each Radio Button using the Value Property of the Radio Button within the Properties Pane.

Radio Buttons can be selected and deselected in the standard manner for the mobile device on which the app runs.

The Radio Button Controls within a group must all be fully within the boundaries of the containing Panel. Versions of MX, the predecessor to Digitise Apps, prior to version 10.3, allowed the controls to only be partially within the Panel. The Allow Control Grouping Property at the Project level allows you to preserve the earlier method of working for backwards compatibility – refer to the Panel Control description below for more details.

Display text e.g. a label or non-editable value.

Generally, this type of Control is used to display information which won't or can't be changed, e.g. to display headings, Control labels or non-editable data. Consequently, by default you cannot associate Scripts with this type of Control. (Scripts allow you to write code to perform a set of actions when specified Events occur, such as when a button is clicked or a Control's value changes.)

However, you can configure the Control to provide an OnClick Event which will be run when the Control is tapped or clicked. To enable the OnClick Event set the Clickable Property for the Control to True in the Properties Pane. To disable the OnClick Event, reset the Property to False.

This Property allows you to provide the ability to trigger a response when static data is clicked or tapped, e.g. you could use it to allow a static phone number to be automatically dialled when the number is clicked or tapped (using the DialTelephone Method within the Control's OnClick Event).

On Android devices, if Haptic Feedback is enabled under the device's operating system's Settings → Sound option the device will vibrate when you tap a Static Text Control which has a script assigned to it.

Display an image or display and play a video. '.bmp', '.jpg', '.png' and '.gif' files are supported for images. '.mp4' files are supported for videos, but other file formats may also work (you will need to experiment on the devices you want to use).

After adding this Control to a form, you need to specify whether the Control is to be used for image or videos in the Control's Video Property. Set this Property to True if you want to use it for videos or False for images. Some of the other Properties will then change depending upon whether you are using images or videos (see below).

If you set the Control to contain images, it will be represented within App Studio's Workspace as an empty square or rectangle with a dotted line border:

If you then specify a specific image to be displayed in the Control, the image will be displayed within the Control's borders, e.g.:

Note that if the image is larger than the size of the Control, only part of the image will appear within the Control's borders:

You can resize the Control to fit the image or use the Mode Property (see below) to specify how the image should be displayed within the Control.

If you set the Control to contain videos, the Control will display a black background with a white play symbol in the centre:

Unlike with images, if you specify a specific video to be displayed in this Control, the representation within App Studio's Workspace won't change and won't display the video. At runtime, however, the Control will display the first frame of the video, unless you configure it to automatically play the video.

Use a Picture & Video Control to Display Images

When working with images, the Picture & Video Control allows you to:

• Display a static named image, i.e. where you want to display a particular image which won't change, such as displaying your organisation's logo in the header on each page.

• Map the Control to a Data Source field, allowing you to read in images from a remote data source, e.g. where you want to download records containing images and display the images on your form.

• Display photos taken with the device's camera.

The behaviour of the Control is controlled by its Properties. Select the Control you want to configure within the Workspace to display its Properties in the Properties Pane.

Within the Properties for a Picture & Video Control, the Image category contains Properties that are specific to Picture & Video Controls. These change depending upon whether you are using the Control to display a picture or a video. These Properties come under the Target property category, allowing you to set different values for different Target Platforms or screen resolutions. The Properties relevant to images are:

Video

Specify whether the Control will be used for pictures or videos. Select True to use the Control for videos or False to specify the Control will be used for pictures. The other Properties in this category will change depending upon the value you select here. The Properties listed below are those relevant to using the Control for pictures.

 

Bitmap

Allows you to specify an image to be displayed in the Control. If you don't map the Control to a remote data source, this image will be static and won't change, e.g. an image of your organisation's logo.

You can either choose from a list of images which have already been imported into the Project or browse for the required file, in which case it will automatically be imported into the Project's Resources and will appear in the Resources Pane. To display a list of the images already imported into the Project, click on the down arrow, , at the right-hand end of the Properties value and then click on the image you want to display.

To browse for the file, click on the browse button, , to the left of the drop-down button. If the browse button isn't visible, click on the Property to select it and then hover your mouse pointer to the left of the drop-down button to display the browse button. A standard Windows file Open dialog will be displayed allowing you to navigate to and select the image you want. Either double-click on the required image or click once to select it and then choose the Open button. Choose the Cancel button instead to close the dialog without selecting a file.

• You can also drag and drop an image (but not a video) from the Resources Pane onto a form, in which case a Picture Control will automatically be added to the form and the Video property will automatically be set to False.

 

Mode

This Property allows you to choose whether to display an image specified in the Bitmap Property at its full size whatever the size of the Control or to resize the image to fit within the Control's boundaries:

Fixed

Image is not rescaled and aligned top-left of control.

 

Auto-Fit

Image is scaled so as to fit exactly into control, loses original aspect ratio.

 

Centre

Image is centred in control, no re-scaling.

 

Centre and Crop

Image scaled uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or larger than the corresponding dimension of the control.

 

Centre Inside

Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or less than the corresponding dimension of the control.

 

Fit Start

Computes a scale that will maintain the original image's aspect ratio, but will also ensure that the image fits entirely inside the control. At least one axis (X or Y) will fit exactly. Aligns the result to the left and top edges of the control.

 

Fit End

Computes a scale that will maintain the original image's aspect ratio, but will also ensure that the image fits entirely inside the control. At least one axis (X or Y) will fit exactly. Aligns the result to the right and bottom edges of the control.

 

Caption

This Property allows you to place a text string over the image, e.g. to give the appearance of a button with an image background.

 

Transparent and Mask Colour

These Properties allow you to make part of an image transparent by specifying a colour to be converted to transparency. All areas of the image coloured with the selected colour will be converted to transparent areas when the image is displayed on the device. For example, if your image has a white background, you could remove the background by selecting white as the colour to be made transparent.

Your selected colour is specified in the Mask Colour Property and the Transparent Property is then used to turn transparency conversion on and off.

The Colour Picker tool, available from the Toolbox Pane, can be used to simplify choosing the Transparency colour. Simply click on the Colour Picker tool and then click on an area of the required colour within the image. The colour will automatically be entered into the Mask Colour Property and the Transparent Property will be set to True. Alternatively, you can click on the browse button, , at the right-hand side of the Property value, to display the Colours dialog box. This dialog allows you to select a colour from a range of standard colours or to manually specify the required colour using RGB values or Hue, Saturation and Luminosity values.

If Transparent is set to True, any areas of the image coloured with the mask colour will be transparent when displayed on the mobile device. App Studio will attempt to display the mask-coloured areas as transparent in order to show you what the effect will be. If Transparent is set to False, the mask colour will be ignored and no areas of the image will be made transparent.

• If your selected picture and the device have different colour densities, the picture will need to be converted when displayed on the device, which may result in the colours in the picture being distorted and there no longer being any pixels that exactly match the specified transparency colour. In this situation you may need to create a version of the picture ('.png' or '.gif') which already includes genuinely transparent areas. In general, we recommend you use a picture which includes the transparency built in as this means the Digitise Apps Client doesn't have to translate the image at runtime, which can slow down the operation of your app.

• On the Apple Platform you cannot use the Transparent and Mask Colour options to define transparent areas of an image with a '.png' file which includes an alpha layer.

 

Opacity

This Property allows you to change the opacity of the image to make it 'see-through'. The value specified here affects the whole image.

This Property can only be changed and is only actioned if the Transparent Property, above, is set to False.

You can change the current value by clicking and dragging the value selector along the bar, using the up and down arrows to the right of the bar or selecting the current value to the left of the bar and typing in a new value (maximum value is 255).

 

Pan & Zoom

This Property allows you provide the ability to pan around a picture and zoom in and out. To do this you need to set the Pan & Zoom Property to True in which case if the user taps or clicks on the Control, at runtime, the OnClick Event will not be triggered and the picture will be displayed full screen. The user can then move the visible portion of the image and zoom in and out using standard mechanisms for their device. To return to the current form, press the device's Back key, or on Apple devices tap the Done button. On Windows devices if there is a Done button, click or tap this button, or alternatively click or tap outside the Pan & Zoom window or press Esc to return to the current form.

Note, that each Platform will have a maximum zoom and if you attempt to enlarge the picture beyond this, the picture may appear to enlarge but snap back to a smaller size when you stop the enlarging action.

On iOS devices, changing the device orientation whilst in pan & zoom mode will close the pan & zoom window and return to the calling form.

 

In addition to the Image category Properties listed above, you should be particularly aware of the following other Properties:

Map to Back Key

This Property, under the Properties Target category, allows you to map a Picture & Video Control to the device's Back key or to a virtual Back key.

Android Devices

If Map to Back Key is set to True for a Control, when the user presses the device's Back key, this will simulate tapping or clicking the mapped Picture & Video Control rather than performing the Back key's standard function.

On forms which have a control mapped to the Back key, the Back key can't then be used to return to the applications page within the Digitise Apps Client. You can, however, always return to the applications page from the menu available by tapping the menu icon, , at the bottom of the screen.

 

Apple and Windows Devices

These devices don't have a hard Back key so setting this Property to True will display a Back button on the left-hand side of the title bar (besides the Home button) instead. Tapping or clicking the button will simulate tapping/clicking the mapped Picture & Video Control.

The Back button will only be displayed on forms which have a Control mapped to the Back key, so if you want the button to be displayed on all screens, you will need to map a Control on each form.

 

In all cases, if the mapped control has a Script assigned to its OnClick Event, this Script will run.

 

By default, the Property is set to False which disables the mapping. If you set this Property on multiple Controls, the Control highest in the Control tree will be the one which is mapped.

Note that if this Property is set to True, the Digitise Apps Client will only action the back key if the Control is enabled.

Button Controls also have a Map to Back key Property.

 

Input

This Property, under the Properties Mapped Data category, allows you to display images downloaded to the device or taken with the device's camera. The data item mapped to the control can have a data type of image, binary or varbinary.

When taking photos on a device, the image is written directly to a Data Source and not to a Picture & Video Control. To display a newly taken photo, you use a Picture & Video Control input mapped to the appropriate field in the Data Source.

 

Output

This Property, under the Properties Mapped Data category, allows you to output map the Control to a Data Source data item. The data item mapped to the control can have a data type of image, binary or varbinary.

 

OnClick

This Property, under the Properties Events category, allows you to assign a Script to the Control, which will be actioned when a user taps or clicks the Control, providing the Pan & Zoom Property described earlier is set to False. It can be used to allow an image to act like a button.

 

• If the Client has a problem loading an image into a Picture & Video Control, e.g. memory issues due to the size of the picture, the file is corrupt or an incorrect format, will be displayed instead of the picture to indicate an error occurred.

  We recommend that, where possible, you create images which are the same size as the Controls which will contain them to reduce the amount of resizing required, which can impact on the performance of the app. In addition, we recommend in general that you take care when using images, especially large images, as using too many images could impact on memory availability resulting in images being unable to be displayed or other performance issues.

  Android Devices

  On Android devices, if you want to display a picture at its actual size, you may need to adjust the size of the image to fit the Picture & Video Control due to the manner in which images are handled on Android devices - pictures are sized using Density Independent Pixels (DIPs) whereas the Control is sized using real physical Pixels. The representation of the form in the Workspace will indicate the size of the current image relative to the size of the form and the Control in which it is contained, allowing you to see whether you need to create a new image for this form. If you are designing for Android devices with different screen resolutions, you can create multiple copies of an image at different sizes and the correct one will automatically be selected for each resolution. For information on creating multiple copies of an image at different sizes and converting from pixel sizes to DIP sizes see Multi-resolution Image Sets on Android Platforms.

• On Android devices if Haptic Feedback is enabled under the device's operating system's Settings → Sound option, the device will vibrate when you tap a Picture & Video Control which has a script assigned to it.

Use a Picture & Video Control to Display Videos

When working with videos, the Picture & Video Control allows you to:

• Display a named video, i.e. where you want to display a particular video which won't change, e.g. a form displaying training videos.

• Map the Control to a Data Source field, allowing you to read in videos from a remote data source, e.g. where you want to download records containing videos and display the videos on your form.

• Display videos taken with the device's camera.

At runtime the Control will display any video content with standard controls for the device it's running on – play, pause, move, full screen etc. The video will automatically be scaled to fit the size of the Control (but see Start Full Screen Property below for Windows devices).

 

The Picture & Video Control will display and run '.mp4' format video files but may also be able to display other video formats as well. If you want to use a different format, try experimenting with your app on the devices you want to use to see if it will work.

 

The behaviour of the Control is controlled by its Properties. Select the Control you want to configure within the Workspace to display its Properties in the Properties Pane.

Within the Properties for a Picture & Video Control, the Image category contains Properties that are specific to Picture & Video Controls. These change depending upon whether you are using the Control to display a picture or a video. These Properties come under the Target property category, allowing you to set different values for different Target Platforms or screen resolutions. The Properties relevant to videos are:

Video

Specify whether the Control will be used for pictures or videos. Select True to specify the Control will be used for videos. The other Properties in this category will change depending upon the value you select here. The Properties listed below are those relevant to using the Control for videos.

 

Content

Allows you to specify a video to be displayed in the Control when the form loads. If you don't input map the Control to a remote data source, this video won't change as the user uses the app.

You can either choose from a list of videos which have already been imported into the Project or browse for the required file, in which case it will automatically be imported into the Project's Resources and will appear in the Resources Pane. To display a list of the videos already imported into the Project, click on the down arrow, , at the right-hand end of the Properties value and then click on the image you want to display.

To browse for the video, click on the browse button, , to the left of the drop-down button. If the browse button isn't visible, click on the Property to select it and then hover your mouse pointer to the left of the drop-down button to display the browse button. A standard Windows file Open dialog will be displayed allowing you to navigate to and select the video file you want. Either double-click on the required video or click once to select it and then choose the Open button. Choose the Cancel button instead to close the dialog without selecting a file.

 

Start Automatically

This Property allows you to automatically run a video displayed in the Control. Set this Property to True to automatically run the video or False to force manual playing of the video. If you specify True, the video will automatically run whenever a RefreshControls or SetControlValue Scripting Method is run on the Control or, for static videos, when the form loads.

 

Loop

This Property allows you to specify that the video should continue running until stopped by the user. If set to True, when the video reaches its end, it will automatically start again from the beginning. If set to False, it will stop running when it reaches the end.

 

Start Full Screen

This Property is only relevant for Windows devices running either a Windows Desktop or UWP version of the Digitise Apps Client or a Digitise Apps Standalone App and determines whether the video should play full screen or not. If set to True, the Control will automatically expand to full screen when a video plays. Set to False, if you don't want the Control to fill the screen.

 

Initial Volume

This Property allows you to set the volume level to be used when a video starts playing.

You can change the current value by clicking and dragging the value selector along the bar, using the up and down arrows to the right of the bar or selecting the current value to the left of the bar and typing in a new value (maximum value is 100).

 

In addition to the Image category Properties listed above, you should be particularly aware of the following other Properties:

Map to Back Key

This Property, under the Properties Target category, allows you to map a Picture & Video Control to the device's Back key or to a virtual Back key. If the Control is set to display videos, this Property will have no effect.

 

Input

This Property, under the Properties Mapped Data category, allows you to display videos downloaded to the device or recorded using the device's camera. Note that Picture & Video Controls can ONLY have an input mapping and can't have an output mapping. The data item mapped to the control can have a data type of image, binary or varbinary.

When shooting videos on a device, the image is written directly to a Data Source and not to a Picture & Video Control. To display a newly recorded video, you use a Picture & Video Control input mapped to the appropriate field in the Data Source.

The Data Source field input mapped to the Control must be configured to store its data to file rather than directly in the local database. Within the input mapping fields, you specify the Data Source field within the database table and Digitise Apps keeps track of the file(s) used to store your video(s) behind the scenes.

 

Output

This Property, under the Properties Mapped Data category, allows you to output map the Control to a Data Source data item. This Property has no effect when the Control is in Video mode.

 

OnClick

This Property, under the Properties Events category, normally allows you to assign a Script to the Control, which would be actioned when a user taps or clicks the Control. However, this Property has no effect when the Control is in Video mode.

 

• If the Client has a problem loading a video into a Picture & Video Control, e.g. memory issues due to the size of the file, the file is corrupt or an incorrect format, an error message may be displayed, depending upon the device, otherwise the video will just not display.

 

Provides ability for user to select a value from a specified range, e.g. 1-199, by moving a pointer along a bar where the left-hand end of the bar represents the lowest value in the range and the right-hand end represents the highest value with intermediate values spread out evenly along the bar between them. The position of the pointer selects the value at that point.

Users select the required value by dragging the slider along the horizontal bar.

Alternatively, you can position the pointer along the bar within a Script using the Control's value Property, an input mapping or the SetControlValue Scripting Method. The position must be a whole number, decimal values are not permitted.

Displays a bar along which a marker travels to provide a visual indication of the progress of an action or process. The position must be a whole number, decimal values are not permitted.

This Control has to be driven from within a Script, e.g. using the SetControlValue Scripting Method or setting the Control's value Property - see Events and Scripts for more details about Scripts and writing your own code segments to perform actions within your apps.

Display a table consisting of multiple rows and columns of data.

This is the only Control which allows you to display data from multiple Data Sources in a single Control.

To mix data from different Data Sources within a ListView Control you can either use a Custom View or a Custom Table.

If you want to use a Custom Table, the data to be displayed must be held in a single table; the Control cannot combine data from multiple tables. Consequently, if you want to combine data from different Data Sources in a ListView you will need to create a Custom Table to hold the combined data and then populate the ListView from the Custom Table.

If you use a Custom View instead, the data is extracted directly from the original Data Sources and you don't need to create a separate Table to hold your data.

Data is displayed within the ListView via a Template which defines the layout and data content of each row within the list. You can also use the Data Conversion facility to change the way data is displayed within the list, e.g. to change coded numeric data to more easily understandable text strings or pictures.

For more information about configuring a ListView see The ListView Control.

SQLServer and SQLite store 1 or 0 in a Bit or Boolean column but will display as "True" and "False" if the value is displayed within a ListView, or other similar Control, within a Digitise app.

Display a date or time with ability to select a different date or time.

The Format Property for the Control determines how the value is displayed within the Control at runtime:

Note that some databases can have regional settings configured on a per-user basis. If you are using Windows authentication to log into the database, the relevant user will be the logged in user running the NDL Digitise App Server service or the user specified within the connection string for this Data Source.

For valid input formats accepted by this Control refer to the SetControlValue Scripting Method.

When extracting the current value in the Control using the GetControlValue Scripting Method, whether entered into the Control locally or from a remote Data Source, the date/time will automatically be converted to a UK format irrespective of the date/time format specified on the device.

If you are input mapping this Control to a Data Field in a Data Source, the Data Field must have a datetime data type.

Trigger a Script to run periodically.

A Timer Control will not start until the form containing it has become visible and it has been enabled.

The Interval Property specifies the time period, in milliseconds, at which to run the Script. Setting the Interval to 0 (or below), will disable the Timer and the Script will not be run.

The Control also has an Enabled Property, which determines whether the Timer should run when the form first loads.

You can change the enabled state of the Control and the timer interval programmatically using the Digitise Apps scripting facility, allowing you to turn the Timer on and off at runtime. See Events and Scripts for more details about actioning commands on a form and the SetTimerInterval Scripting Method for Script Methods relevant to using a Timer Control.

You can choose whether you want a Timer to continue to run when the form which launches it is hidden, using the Control's Active on Parent Form Only Property.

If this Property is set to True, the Timer will not trigger the OnTimer Event when the form to which it belongs is not the current form, i.e. when another form is displayed. If the form returns to being the current form, the OnTimer Event will trigger again.

If set to False, the OnTimer Event will continue to trigger whichever form is current, unless you disable it within your Script.

For backwards compatibility, apps created with a version of MX, the predecessor to Digitise Apps, prior to v10, will have this Property set to False.

The default value for new Timer Controls added to a form is True.

In addition to the Timer Control, which you can place on individual forms as required, there is also a Global Timer available which is form independent. This Timer is automatically available in every app and doesn't need to be placed on a particular form. Hence it isn't available in the Toolbox Pane. For more information about the Global Timer see the OnTimer Event and the SetGlobalTimerInterval Scripting Method.

Write or draw directly on the screen within the boundaries of the Control.

The Control's Bitmap Property allows you to display an image within the Control that the user can write or draw over to provide a pictorial record of information, for example to indicate a location on a map or the position of a wound on a patient's body.

The Mode Property allows you to specify whether the image should be displayed at its actual size irrespective of the size of the Control or enlarged or shrunk to fit within the Control:

If the Client has a problem loading an image into the Control, e.g. memory issues due to the size of the picture, the file is corrupt or an incorrect format, will be displayed instead of the picture to indicate an error occurred.

We recommend that, where possible, you create images which are the same size as the Controls which will contain them to reduce the amount of resizing required, which can impact on the performance of the app. In addition, we recommend in general that you take care when using images, especially large images, as using too many images could impact on memory availability resulting in images being unable to be displayed or other performance issues.

Note that on Android devices, if you want to display a picture at its actual size, you may need to adjust the size of the image to fit the Picture Control due to the way in which images are handled on these devices - pictures are sized using Density Independent Pixels (DIPs) whereas the Control is sized using real physical Pixels. App Studio will indicate the size of the current image on the form, allowing you to see whether you need to create a new image for this form. If you are designing for Android devices with different screen resolutions, you can create multiple copies of an image at different sizes and the correct one will automatically be selected for each resolution. For information on creating multiple copies of an image at different sizes and converting from pixel sizes to DIP sizes see Multi-resolution Image Sets on Android Platforms.

If the Control has an output mapping, the image will automatically be saved to the current record in the appropriate Data Source in 'jpg' format.

The Foreground Colour of the current style assigned to the Control determines the colour of the line drawn. The SetControlTextColour Scripting Method can be used to change the line colour at runtime providing a means to identify different things in the same Control.

Note that the RefreshControls Scripting Method does not clear user added drawing or writing from this Control. If you want to clear user input, you will need to use the ClearControl Scripting Method before calling RefreshControls.

Allows you to create a container for one or more Controls which when upscaling a form will reposition the Controls relative to the Panel's boundaries rather than the form.

If a Panel contains Radio Buttons, the Radio Buttons contained within the Panel will act as a group of mutually-exclusive Radio Buttons, i.e. selecting one Radio Button will automatically deselect the existing selection and only one Radio Button in the group will be able to be selected at any one time.

Within App Studio when designing your form, you must click on the Panel's boundary in order to select the Panel. If you want to drag the Panel to a new location, you must also position the mouse pointer on the control's boundary or use the small square which appears in the Panel's top left-hand corner when the Panel is selected. Moving a Panel will also move any Controls contained within it. If you want to move the Panel without moving the Controls contained within it, hold down Ctrl+Shift whilst moving the Panel with your mouse.

You can also select a Panel by clicking on the form outside the Panel and then, keeping the left mouse button held down, draw a selection rectangle around the Control. Other operations such as resizing or copying a Panel do not affect the Controls contained within the Panel. If you want to perform an operation on all the Controls within the Panel as well as on the Panel, you will need to select all the items you want to be acted upon before you perform the action.

To add Controls to a Panel, draw your Panel on the form and then draw the required Controls on top of the Panel. Alternatively, you can drag and drop a Control from elsewhere on the form onto the Panel. The Control must fall entirely within the boundaries of the Panel to be contained within it.

In addition, a Control will only be contained within the Panel if the Panel is above the Control in the tree view displayed in the Forms Pane. This means you can exclude a Control from a surrounding Panel by moving the Control in the tree view so that the Control is higher in this tree than the Panel.

You can also exclude or include a Control using its Can Group Property. If this Property is set to True and the Control falls within the Panel's boundary and the Panel item is higher than the Control item in the Forms Pane tree view, the Control will be contained within the Panel. If set to False, the Control will not be contained within the Panel even if it matches the criteria for inclusion.

A Control's Group Control Property indicates whether the Control is contained within a surrounding Panel or not by displaying the name of the Panel if the Control is contained within the Panel. If this Property is blank the Control is not contained within a Panel.

Note that if a Control is contained within a Panel on one of a Platform's screen resolutions, it will be contained within the Panel on all resolutions, even if it isn't within the Panel's boundaries on the other resolutions.

When you move a Panel, any Controls which after the move now fall completely within the Panel's boundaries will automatically be added to the Panel, providing the other conditions for including a Control within a Panel mentioned above are met.

You can enable/disable and hide/show a Panel in the Panel's Properties or programmatically within your Scripts. These operations will affect any Controls contained within the Panel, so if you hide a Panel all the Control's contained within it will also be hidden. Note, however, that if you have a Control contained within a Panel which is disabled or hidden independently of the Panel, e.g. using the Control's Properties at design time, if the containing Panel is enabled or shown at runtime, the Control will also be enabled or shown. If you don't want the Control to be enabled or shown along with the Panel, after enabling or showing the Panel, you will need to programmatically disable or hide the Control separately.

A Panel can contain other Panels.

If a form is displayed on a device which has a larger screen than that of the form's original Target Platform and the form is being upscaled to fit the current screen, Controls contained within a Panel will be repositioned according to their Repositioning Properties in relation to the Panel's boundaries and not in relation to the form.

The behaviour of the Panel Control is affected by the Allow Control Grouping Property in the Project Properties. By default, for new Projects, this Property is set to True which means that Panels will behave as described above. For existing Projects, created using v10.2 or earlier of Digitise Apps' predecessor MX, this Property will be set to False, which means that the Panel Control will revert to working as it did in MX v10.2 and earlier. In this case the Panel can only be used to group Radio Buttons and doesn't influence repositioning of Controls when upscaling. You can change the value of this Property if you want to allow existing Projects to take advantage of the extended behaviour.

There is also a special type of Panel which is used within ListView Templates to define the height and width of a row within the ListView.

Allows you to display text with formatting to give more control over the look of your forms. Formatting is achieved using a subset of HTML.

To display formatted text in the Control you set the Control's value to a string including HTML tags to provide the formatting.

The following HTML tags are supported on all Platforms:

In addition to the tags listed above individual Platforms may support other tags and attributes depending upon the support offered by the device and operating system version you are using. If you want to maintain cross-platform compatibility, we recommend that you only use the tags listed above.

On the Android Platform you can also use the <font> tag to change text colour, e.g. <font color="red">Warning!</font>

but other <font> attributes are not supported.

On Windows Desktop and Windows Universal Platforms, if you want to change the appearance of the text you must use the style attribute of a tag, e.g. <p style="color: red; font-size: 24px">Warning!</p>

The <font> tag is not supported on these Platforms.

The following additional tags are also supported on the Windows Desktop and Windows Universal Platforms:

On the Apple Platform you can use either the <font> tag or the style attribute of a tag to specify text properties. In addition to the tags listed above, iOS supports a large subset of CSS and HTML tags and their attributes but support varies by iOS version and so if you want to try any tags other than those listed, we recommend testing your app on a real device before deploying it.

On Android and iOS Platforms, the appearance of the Control and the text within it can also be configured by applying a style to the Control in App Studio. The following elements of a Digitise Apps style are applied to the Control if they are not set to default:

If you want to assign a value to the Control within your Project, you use the Caption Property of the Control. Select the Property in the Properties Pane and then click on the Browse button which appears to the right of the Property's value field. This will display the HTML Editor dialog box which allows you to enter your required HTML string in the top half of the dialog and then click on the Preview button to display a representation of your HTML in the lower half of the dialog.

Note that the preview is only intended to provide a guide to what your formatted text might look like and does not signify that your entered string will work and display exactly as shown here when displayed on your mobile devices. We recommend that you always test your text on a real device to be sure that the HTML entered is supported on the device and how it will appear at runtime.

At runtime you can assign a value to the Control using the SetControlValue Scripting Method or via an input data mapping. Reading the current value using the GetControlValue Scripting Method will return the HTML string including any tags.

If you want to display more than a single line in the Control, you will need to set the Control's Multiline Property toTrue, in which case the user will be able to scroll up and down within the Control.

By default, the Control does not respond to mouse clicks or taps. If you want to enable an OnClick Event for the Control you will need to set the Control's Clickable Property to True.